Orders

Order objects are created to handle end customers' purchases of already existing products. You can create, retrieve and update individual orders, as well as list all orders. Orders are identified by a unique autogenerated ID as well as an external ID set by yourself.

Base URL

All following endpoints operates over the URL of your store: https://your-store.com/

example: https://alephdigital.publica.la/

Endpoints

• Create permission Order
• Create Report Order
• Create sale Order

For all type of Order

• Get
• Update
• Cancel

Headers

{
  "Content-Type": "application/json",
  "Accept": "application/json",
  "X-User-Token": {api_token}
}

info

Make sure you generated the api_token on your store. More info HERE

First of all, there are three types of orders.

• Permission orders: Used to assign a publication or plan to a user. Although it grants access, it doesn't count as a transaction in the sales report, and therefore, it won't be displayed in the sales report.
• Report orders: Allows the creation of users and products if they do not exist, assigns a publication or plan to a user, generates a transaction in the sales report without going through a gateway, and automatically marks it as approved by default.
• Sale orders: Used to generate a checkout session in a gateway. The order will remain in the 'pending' status until the user completes its payment in the gateway. If the payment is successful, the order then transitions to the 'approved' status. Once the order transitions to the 'approved' status, it can be viewed in Dashboard-Sales. This order also grants access to a publication or plan, and it will be reported as a transaction in the sales report.

Create Permission

POST /integration-api/v1/orders

example: https://your-store.com/integration-api/v1/orders

Automatic creation of missing resources:

When creating sale,permission and report orders, if the user doesn't exist, it's created automatically. That's why the user.id is required.

Body Request for permission

Field	Description	Required	Type	Format
type	Order type	yes	string	permission
external_reference	Order unique ID in your system	no	string	max 64
return_url	An url to return to, after finishing the checkout	no	string	url
unit_price	Order price	no	float
currency_id	Order currency	no	string	ISO 4217. All supported for permission. Only ARS supported for sale or report
user	User object	yes	object
user.id	User unique ID in your system	yes	string	max 64
user.email	User Email	yes	string	email
products	List of products	yes	objects array
products.*.type	Product type	yes	string	content or subscription
products.*.id	Product unique ID in your system	yes	string	max 64
products.*.name	Product name	no	string	max 64. (*) It's required only when using the automatic creation of products
products.*.url	Product url	no	string	url. (*) It's required only when using the automatic creation of products
products.*.unit_price	Product price	no	float
products.*.currency_id	Product currency	no	string	ISO 4217. All supported for permission. Only ARS supported for sale or report
products.*.expiration_date	User will lose access to the content at this date	no	string	yyyy-mm-dd

JSON example for permission order:

{
 "external_reference": "123-abc",
 "user":{
  "id": "123",
  "email": "[email protected]"
 },
 "products": [{
  "id": "123",
  "type": "content",
  "expiration_date": "2023-12-31"
 }]
}

Response

Field	Description	Type	Format
id	publica.la's order unique ID	string
external_reference	Order unique ID in your system	string
type	Order creation type	string	permission
unit_price	Order price	float
currency_id	Order currency	string	ISO 4217
status		string
created_at	Date when the order was created.	string	yyyy-mm-dd
user		object
user.id	User unique ID in your system	string	max 64
user.email	User email	string	email
products	List of products	objects array
products.*.id	Product unique ID in your system	string
products.*.type		string	content or subscription
products.*.name		string
products.*.status		string
products.*.expiration_date	User will lose access to the content at this date	string	yyyy-mm-dd
products.*.cover		string
products.*.reader_url		string
products.*.unit_price		float

JSON example for permission:

{  
  "data":
   {
     "id" : "03033649-de10-404b-aa8a-8682871001c2",
     "external_reference": "123-abc",
     "type": "permission",
     "unit_price": 12.9,
     "currency_id": "USD",
     "status": "approved",
     "created_at": "2021-08-01",
     "user":{
        "id": "123",
        "email": "[email protected]"
     },
     "products": [{
          "id": "abc-123",
          "type": "content",
          "name": "abc product",
          "status": "approved",
          "expiration_date": "2021-12-31",
          "cover": "https://cdn.publica.la/item/3213123.jpg",
          "reader_url": "https://domain.com/reader/abc-product",
          "description": "abc product is...",
          "pages_quantity": 12,
          "file_type": "pdf",
          "is_free": false,
          "unit_price": 10
     }]
   }
}

Create Report

POST /integration-api/v1/orders

example: https://your-store.com/integration-api/v1/orders

Automatic creation of missing resources:

When creating sale,permission and report orders, if the user doesn't exist, it's created automatically. That's why the user.id is required.

Body Request for Report

Field	Description	Required	Type	Format
type	Order type	yes	string	report
external_reference	Order unique ID in your system	no	string	max 64
return_url	An url to return to, after finishing the checkout	yes	string	url
unit_price	Order price	yes	float
currency_id	Order currency	yes	string	ISO 4217. All supported for permission. Only ARS supported for sale
user	User object	yes	object
user.id	User unique ID in your system	yes	string	max 64
user.email	User Email	no	string	email
products	List of products	yes	objects array
products.*.type	Product type	yes	string	content or subscription
products.*.id	Product unique ID in your system	yes	string	max 64
products.*.name	Product name	yes*	string	max 64. (*) It's required only when using the automatic creation of products
products.*.url	Product url	yes*	string	url. (*) It's required only when using the automatic creation of products
products.*.unit_price	Product price	yes	float
products.*.currency_id	Product currency	yes	string	ISO 4217. All supported for permission. Only ARS supported for sale or report
products.*.expiration_date	User will lose access to the content at this date	no	string	yyyy-mm-dd

JSON example for sale order:

{
  "unit_price": 25,
  "type": "report",
  "currency_id": "USD",
  "return_url": "https://www.google.com",
  "user":{
    "email": "[email protected]"
  },

  "products": [{
    "id": "product-002",
    "type": "content",
    "unit_price": 25,
    "currency_id": "USD"
  }]
}

Response

Field	Description	Type	Format
id	publica.la's order unique ID	string
external_reference	Order unique ID in your system	string
type	Order creation type	string	sale
unit_price	Order price	float
currency_id	Order currency	string	ISO 4217
status		string
created_at	Date when the order was created.	string	yyyy-mm-dd
user		object
user.id	User unique ID in your system	string	max 64
user.email	User email	string	email
products	List of products	objects array
products.*.id	Product unique ID in your system	string
products.*.type		string	content or subscription
products.*.name		string
products.*.status		string
products.*.expiration_date	User will lose access to the content at this date	string	yyyy-mm-dd
products.*.cover		string
products.*.reader_url		string
products.*.unit_price		float

**JSON example for report:

{
  "data": {
    "id": "d052f749-6bab-40d7-b188-24fbad7bc97a",
    "external_reference": null,
    "type": "report",
    "unit_price": 25,
    "currency_id": "USD",
    "user": {
      "id": null,
      "email": "[email protected]"
    },
    "status": "approved",
    "created_at": "2024-05-09",
    "products": [
      {
        "id": "product-002",
        "type": "content",
        "name": "product-002",
        "status": "approved",
        "expiration_date": null,
        "unit_price": 25,
        "currency_id": "USD",
        "cover": "https://farfalla.localhost/images/cover-image-02.png",
        "reader_url": "http://farfalla.localhost"
      }
    ]
  }
}

Create Sale

POST /integration-api/v1/orders

example: https://your-store.com/integration-api/v1/orders

Automatic creation of missing resources:

When creating sale,permission and report orders, if the user doesn't exist, it's created automatically. That's why the user.id is required.

When creating sale orders only, if the product doesn't exist, it's created automatically. For this to happen, we need the product fields name and url, in addition to the fields already "required for sale".
The newly created product will be type "External link" and it will be pointing to that url. It will only be accessible through the API or the store dashboard, it won't be displayed in the storefront.

Completing the checkout for sale orders

When creating a sale order, the response will include a checkout.token property containing an external-auth-token url and checkout.ttl with its ttl in seconds. You should redirect your user to that URL, and we'll automatically authenticate them and redirect them to the corresponding gateway checkout. After they complete the payment, they will be redirected to the return_url you set for your order.
We will add a query string to that return_url containing the following payment data:

• order-id: The order ID in our system
• order-external-id: The order ID in your system
• status: the resulting status after the payment (approved, pending, cancelled)

Keep in mind that a checkout.token expires after checkout.ttl seconds, you can always generate a new one manually or by retrieving the order using the GET endpoint

Body Request for Sale

Field	Description	Required	Type	Format
type	Order type	yes	string	sale
external_reference	Order unique ID in your system	no	string	max 64
return_url	An url to return to, after finishing the checkout	yes	string	url
unit_price	Order price	yes	float
currency_id	Order currency	yes	string	ISO 4217. All supported for permission. Only ARS supported for sale
user	User object	yes	object
user.id	User unique ID in your system	yes	string	max 64
user.email	User Email	no	string	email
products	List of products	yes	objects array
products.*.type	Product type	yes	string	content or subscription
products.*.id	Product unique ID in your system	yes	string	max 64
products.*.name	Product name	yes*	string	max 64. (*) It's required only when using the automatic creation of products
products.*.url	Product url	yes*	string	url. (*) It's required only when using the automatic creation of products
products.*.unit_price	Product price	yes	float
products.*.currency_id	Product currency	yes	string	ISO 4217. All supported for permission. Only ARS supported for sale or report
products.*.expiration_date	User will lose access to the content at this date	no	string	yyyy-mm-dd

JSON example for sale order:

{
     "external_reference": "123-abc",
     "type": "sale",
     "unit_price": 10,
     "currency_id": "ARS",
     "user":{
        "id": "123",
        "email": "[email protected]"
     },
     "products": [{
        "id": "123",
        "type": "content",
        "unit_price": 10,
        "currency_id": "ARS"
     }]
 }

Response

Field	Description	Type	Format
id	publica.la's order unique ID	string
external_reference	Order unique ID in your system	string
type	Order creation type	string	sale
unit_price	Order price	float
currency_id	Order currency	string	ISO 4217
status		string
created_at	Date when the order was created.	string	yyyy-mm-dd
user		object
user.id	User unique ID in your system	string	max 64
user.email	User email	string	email
products	List of products	objects array
products.*.id	Product unique ID in your system	string
products.*.type		string	content or subscription
products.*.name		string
products.*.status		string
products.*.expiration_date	User will lose access to the content at this date	string	yyyy-mm-dd
products.*.cover		string
products.*.reader_url		string
products.*.unit_price		float

JSON example for sale (when just created and still pending):

{  
  "data":
   {
     "id" : "03033649-de10-404b-aa8a-8682871001c2",
     "external_reference": "123-abc",
     "checkout": {
        "url": "https://your-store.com/auth/token?external-auth-token={AUTH-TOKEN}",
        "expires_on" : "2023-01-01 12:00:00"
   },
     "type": "sale",
     "unit_price": 10,
     "currency_id": "ARS",
     "status": "pending",
     "created_at": "2021-08-01",
     "user":{
        "id": "123",
        "email": "[email protected]"
     },
     "products": [{
          "id": "abc-123",
          "type": "content",
          "name": "abc product",
          "status": "pending",
          "cover": "https://cdn.publica.la/item/3213123.jpg",
          "reader_url": "https://domain.com/reader/abc-product",
          "description": "abc product is...",
          "pages_quantity": 12,
          "file_type": "pdf",
          "is_free": false
     }]
 }
}

Code	Description
200	Ok
201	Object Created
422	Validation error, the reason of the error will be described in the response body
401	Unauthenticated

JSON with errors example:

{
    "status": 422,
     "errors": [{
          "title": "Incorrect User ID",
          "details": ["Creation of the order failed due to incorrect user id"]
     }]
}

Get

Using this endpoint you can either paginate through all the orders, search for orders by different parameters, or get a specific order by ID

GET /integration-api/v1/orders/{id || external_reference}?id_type= &user_email= &product_id &product_type= &start_at= &end_at=

tip

Using query parameter you can filter by id_type, user_email, product_id, product_type, or by date range using start_at, end_at.

examples:

• Getting a specific order by the ID in our system:
  https://your-store.com/integration-api/v1/orders/some-id?id_type=internal
• Getting a specific order by the ID in your system:
  https://your-store.com/integration-api/v1/orders/some-other-id?id_type=external
• Searching for orders by product_id
  https://your-store.com/integration-api/v1/orders?product_id=some-product-id&product_type=content
• Searching for orders by date range
  https://your-store.com/integration-api/v1/orders?start_at=2022-01-01&end_at=2022-06-01
• Searching for orders by user email
  https://your-store.com/integration-api/v1/[email protected]
• Getting all your orders
  https://your-store.com/integration-api/v1/orders

Parameters

Field	Description	Type	Required	Format
id	Main or internal Order ID	string	no	max 64
external_reference	External reference or order ID	string	only if id_type=external	max 64

Query Params

Field	Description	Type	Required	Format
id_type	ID type	string	only when we set an ID or external_reference parameter	internal or external
user_id	User unique ID in your system	string	It is prioritized over user_email	max 64
user_email	User Email	string		email
product_type		string	only when we set a product_id	content or subscription
product_id	Product ID in your system	string		max 64
start_at	Date when the order was created	string		yyyy-mm-dd
end_at	Date when the order was created	string		yyyy-mm-dd

Response

Field	Description	Type	Format
id	publica.la's order unique ID	string
external_reference	Order unique ID in your system	string
checkout.token	When the order is pending, the url to continue the checkout	string
checkout.ttl	When the order is pending, the ttl in seconds	integer
type	Order creation type	string	internal,sale,permission and report
unit_price	Order price	float
currency_id	Order currency	string	ISO 4217
created_at	Date when the order was created.	string	yyyy-mm-dd
status	Status of the order	string	approved, cancelled, pending, paused
user	Contains details of the user.	object
user.id	User unique ID in your system	string
user.email	User Email	string
products	Contains details of the product.	array object	Contains details of the products.
products.id	Product unique ID in your system	string
products.type		string	content or subscription
products.name		string
products.status		string
products.expiration_date	User will lose access to the content at this date	string	yyyy-mm-dd
products.cover		string
products.reader_url		string
products.unit_price		float

JSON example:

{"data": [{
          "id": "c9f2b7b0-dc74-4c58-92a7-9dfcf93aed38",
          "external_reference": "123-abc",
          "unit_price": 17,
          "currency_id": "USD",
          "type": "sale",
          "user": {
               "id": "123",
               "email": "[email protected]" 
          },
          "status": "approved",
          "created_at": "2022-01-18",
          "products": [
               {
                    "id": "978-987-805-082-9",
                    "type": "content",
                    "name": "Lorem Ipsum",
                    "cover": "https://storage/thumbnail.jpg",
                    "expiration_date": "2023-12-31",
                    "reader_url": "https://domain.com/reader/lorem-ipsum",
                    "description": "",
                    "pages_quantity": 324,
                    "file_type": "PDF",
                    "is_free": false,
                    "unit_price": 17,
                    "status": "approved"
               }
          ]
          }]
}

Update

PUT /integration-api/v1/orders/{id || external_reference}?id_type=

example: https://your-store.com/integration-api/v1/orders/123-abc?id_type=external

This endpoint can update:

• expiration date
• status

note

At least one of the two values is required.

status can change as follows:

• status: paused Only those orders Approved
• status: cancelled Only those orders Paused o Approved
• status: approved Only those orders Paused

note

• If expiration_date is sent as null, it is interpreted that expiration_date should be removed and left null
• The status cancelled is a final status which cannot be modified. :::

Parameters

Field	Description	Type	Required	Format
id	Main or internal Order ID	string	yes, when we don’t have an external_reference	max 64
external_reference	External reference or order ID	string	yes, when we don't have an id	max 64

Query params

Field	Required	Type	Format
id_type	yes, when using external_reference it should be external	string	internal or external
product_id	no	string	max 64
product_type	Conditional. Required if product_id is not null.	content or subscription

Body request

Field	Required	Type	Format
expiration_date	Conditional. Required if status is null.	string	yyyy-mm-dd
status	Conditional. Required if expiration_date is null.	string	cancelled, approved or paused

{
    "expiration_date": "2023-12-31",
    "status" : "paused"
}

Response

Field	Description	Type	Format
id	publica.la's order unique ID	string
external_reference	Order unique ID in your system	string	string
type	Order creation type	string	internal, sale, permission or report
unit_price	Order price	float
currency_id	Order currency	string	ISO 4217
created_at	Date when the order was created.	string	yyyy-mm-dd
status	Status of the order	string	approved, cancelled, pending, paused
user	Contains details of the user.	object
user.id	User unique ID in your system	string
user.email	User Email	string
products	Contains details of the product.	array object	Contains details of the products.
products.id	Product unique ID in your system	string
products.type		string	content or subscription
products.name		string
products.status		string
products.expiration_date	User will lose access to the content at this date	string	yyyy-mm-dd
products.cover		string
products.reader_url		string
products.unit_price		float

JSON example:

{  
  "data": {
     "id": "03033649-de10-404b-aa8a-8682871001c2",
     "external_reference": "123-abc",
     "unit_price": 12.9,
     "currency_id": "USD",
     "user":{
        "id": "123",
        "email": "[email protected]"
     },
     "status": "approved",
     "created_at": "2020-04-13",
     "products": [
         {
          "id": "abc-123",
          "type": "content",
          "name": "abc product",
          "expiration_date": "2023-12-13",
          "cover": "https://cdn.publica.la/item/3213123.jpg",
          "reader_url": "https://domain.com/reader/abc-product",
          "description": "abc product is...",
          "pages_quantity": 12,
          "file_type": "PDF",
          "is_free": false,
          "unit_price": 10,
           "status": "approved"
        }
     ]
  }
}

Code	Description
200	Ok
201	Object Created
422	Validation error, the reason of the error will be described in the response body
401	Unauthenticated

JSON with errors example:

{
    "status": 422,
     "errors": [{
          "title": "Incorrect expiration date format",
          "details": ["Update failed due to incorrect expiration date format"]
     }]
}

Cancel

DELETE /integration-api/v1/orders/{id || external_reference}?id_type=

example: https://your-store.com/integration-api/v1/orders/123-abc?id_type=external

Once deleted, the cancelled status cannot be reversed. :::

Parameters

Field	Description	Type	Required	Format
id	Main or internal Order ID	string	yes, when we don’t have an external_reference	max 64
external_reference	External reference or order ID	string	yes, when we don't have an id	max 64

Query params

Field	Required	Type	Format
id_type	yes, when using external_reference it should be external	string	internal or external

Body request

Field	Description	Required	Type	Format
reason	Set a reason why you cancel or revoke the access to the user.	no	string	max 150
expiration_date	User will lose access to the content at this date. If it is not specified and it is a subscription, it will be canceled once the current period has ended, otherwise the cancellation will be immediate.	no	string	yyyy-mm-dd

Response

Field	Description	Type
id	Main or internal order ID	string
external_reference	External reference or order ID	string

JSON example:

{  
  "data": [
   {
     "id": "03033649-de10-404b-aa8a-8682871001c2",
     "external_reference": "123-abc"
   }
  ]
}

Code	Description
200	Ok
422	Validation error, the reason of the error will be described in the response body
401	Unauthenticated